<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Building replicated applications</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="rep.html" title="Chapter 13.  Berkeley DB Replication" />
    <link rel="prev" href="rep_pri.html" title="Replication environment priorities" />
    <link rel="next" href="rep_mgr_meth.html" title="Replication Manager methods" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Building replicated applications</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="rep_pri.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 13.  Berkeley DB Replication </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep_mgr_meth.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="rep_app"></a>Building replicated applications</h2>
          </div>
        </div>
      </div>
      <p>
        The simplest way to build a replicated Berkeley DB
        application is to first build (and debug!) the transactional
        version of the same application. Then, add a thin replication
        layer: application initialization must be changed and the
        application's communication infrastructure must be
        added.
    </p>
      <p>
        The application initialization changes are relatively
        simple. Replication Manager provides a communication
        infrastructure, but in order to use the replication Base APIs
        you must provide your own.
    </p>
      <p>
        For implementation reasons, all replicated databases must
        reside in the data directories set from <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV-&gt;add_data_dir()</a> (or
        in the default environment home directory, if not using
        <a href="../api_reference/C/envadd_data_dir.html" class="olink">DB_ENV-&gt;add_data_dir()</a>), rather than in a subdirectory below the
        specified directory. Care must be taken in applications using
        relative pathnames and changing working directories after
        opening the environment. In such applications the replication
        initialization code may not be able to locate the databases,
        and applications that change their working directories may
        need to use absolute pathnames.
    </p>
      <p>
        During application initialization, the application performs
        three additional tasks: first, it must specify the
        <a href="../api_reference/C/envopen.html#envopen_DB_INIT_REP" class="olink">DB_INIT_REP</a> flag when opening its database environment and
        additionally, a Replication Manager application must also
        specify the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag; second, it must provide Berkeley
        DB information about its communications infrastructure; and
        third, it must start the Berkeley DB replication system.
        Generally, a replicated application will do normal Berkeley DB
        recovery and configuration, exactly like any other
        transactional application.
    </p>
      <p>
        Replication Manager applications configure the built-in
        communications infrastructure by calling obtaining a <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a>
        handle, and then using it to configure the local site. It can
        optionally obtain one or more <a href="../api_reference/C/db_site.html" class="olink">DB_SITE</a> handles to configure
        remote sites. Once the environment has been opened, the
        application starts the replication system by calling the
        <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV-&gt;repmgr_start()</a> method. 
    </p>
      <p>
        A Base API application calls the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> method to
        configure the entry point to its own communications
        infrastructure, and then calls the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a> method to join
        or create the replication group.
    </p>
      <p>
        When starting the replication system, an application has two
        choices: it may choose the group master site explicitly, or
        alternatively it may configure all group members as clients
        and then call for an election, letting the clients select the
        master from among themselves. Either is correct, and the
        choice is entirely up to the application.
    </p>
      <p>
        Replication Manager applications make this choice simply by
        setting the flags parameter to the <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV-&gt;repmgr_start()</a>
        method.
    </p>
      <p>
        For a Base API application, the result of calling <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a>
        is usually the discovery of a master, or the declaration of
        the local environment as the master. If a master has not been
        discovered after a reasonable amount of time, the application
        should call <a href="../api_reference/C/repelect.html" class="olink">DB_ENV-&gt;rep_elect()</a> to call for an election.
    </p>
      <p>
        Consider a Base API application with multiple processes or
        multiple environment handles that modify databases in the
        replicated environment. All modifications must be done on the
        master environment. The first process to join or create the
        master environment must call both the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> and the
        <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a> method. Subsequent replication processes must at
        least call the <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> method. Those processes may call
        the <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a> method (as long as they use the same master or
        client argument). If multiple processes are modifying the
        master environment there must be a unified communication
        infrastructure such that messages arriving at clients have a
        single master ID. Additionally the application must be
        structured so that all incoming messages are able to be
        processed by a single <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle.
    </p>
      <p>
        Note that not all processes running in replicated
        environments need to call <a href="../api_reference/C/repmgrstart.html" class="olink">DB_ENV-&gt;repmgr_start()</a>, <a href="../api_reference/C/reptransport.html" class="olink">DB_ENV-&gt;rep_set_transport()</a> or
        <a href="../api_reference/C/repstart.html" class="olink">DB_ENV-&gt;rep_start()</a>. Read-only processes running in a master
        environment do not need to be configured for replication in
        any way. Processes running in a client environment are
        read-only by definition, and so do not need to be configured
        for replication either (although, in the case of clients that
        may become masters, it is usually simplest to configure for
        replication on process startup rather than trying to
        reconfigure when the client becomes a master). Obviously, at
        least one thread of control on each client must be configured
        for replication as messages must be passed between the master
        and the client.
    </p>
      <p>
        Any site in a replication group may have its own private
        transactional databases in the environment as well. A site may
        create a local database by specifying the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_TXN_NOT_DURABLE" class="olink">DB_TXN_NOT_DURABLE</a>
        flag to the <a href="../api_reference/C/dbset_flags.html" class="olink">DB-&gt;set_flags()</a> method. The application must never
        create a private database with the same name as a database
        replicated across the entire environment as data corruption
        can result.
    </p>
      <p>
        If encryption is desired in a replicated application, all sites
        in the replication group must use encryption. The use of a secure
        transport is strongly recommended because some log and database
        information is transmitted between sites in unencrypted form.
    </p>
      <p>
        For implementation reasons, Base API applications must
        process all incoming replication messages using the same <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
        handle. It is not required that a single thread of control
        process all messages, only that all threads of control
        processing messages use the same handle.
    </p>
      <p>
        No additional calls are required to shut down a database
        environment participating in a replication group. The
        application should shut down the environment in the usual
        manner, by calling the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> method. For Replication
        Manager applications, this also terminates all network
        connections and background processing threads.
    </p>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="rep_pri.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep_mgr_meth.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Replication environment priorities </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Replication Manager methods</td>
        </tr>
      </table>
    </div>
  </body>
</html>
